Java Programming Style Guide

1 Local Style Guide

You must follow certain guidelines when writing Java code.

Each class must be in its own file.
The name of the file and the name of the class must coincide exactly. For example the Queue class should be in a file named Queue.java. Note that Java is case-sensitive (even though Windows NT really isn't).
Class names must start with an uppercase letter.
In addition, each "word" within a class name should start with an uppercase letter. For example, TextMessage and SimpleTrafficMonitor are both appropriate class names.
The names of "constants" (i.e., final variables) must be in all uppercase.
Other variable and method names that contain multiple characters must not start with an uppercase letter.
Further, each "word" within a variable name should start with an uppercase letter. For example, importantMessage and campusMonitor are both appropriate variable names.
Variable names that consist of a single character may be uppercase.
In general, even single-character variable names should be lowercase. However, in some situations, mathematical notation uses uppercase letters. In such situations, uppercase variable names may be used. For example, matrices are often written using uppercase letters. So, an expression like (b = A*x) would be appropriate.
Variable and method/function names must be descriptive.
Variable names like aaa are not appropriate. Index variables and counters can, however, have names like i and j.

Methods within a class must be listed in alphabetical order.

The only exception to this rule is that all constructors must be listed first. For example, in a Queue class, the constructor(s) should be first, the pop method should be second, and the push method should be third.

javaexamples/Queue.java

/**
 * A Queue of Object elements.
 *
 * @version 0.0
 * @author  CS Dept., James Madison University
 *
 * This work complies with the JMU Honor Code
 */
public class Queue
{
    private int  size;
    private Node back, front;


    /**
     * Construct a new (empty) Queue.
     */
    public Queue()
    {
        front = null;
        size  = 0;
    }

    /**
     * Pop an Object off of the front of this Queue.
     *
     * @return  The Object on the front of this Queue
     */
    public Object pop()
    {
        Object  value;

        if (front != null)
        {
            value = front.value;
            front = front.next;
            size--;
        } 
        else 
        {
            value = null;
        }

        return value;
    }


    /**
     * Push an Object onto the back of this Queue.
     *
     * @param o   The Object to push
     */
    public void push(Object o)
    {
        Node temp;

        temp       = new Node();
        temp.value = o;
        temp.next  = null;

        if (front == null) 
        {
            front = temp;
        } 
        else 
        {
            back.next = temp;
        }

        back = temp;
        size++;
    }

    /**
     * Get the number of elements in this Queue.
     *
     * @return  The number of elements
     */
    public int size()
    {
        return size;
    }
}

All variables must be declared at the top of the relevant class or method (with two exceptions).
So, class variables should be declared at the top of the class (before any methods are declared) and variables that are local to a method should be declared at the top of that method (before any other lines of code). The only exceptions to this rule are:

In the constructor of a derived class the call to the constructor of the parent class must come first.

Index variables in loops may be declared locally.
All variables must be declared alphabetically by their class/type.
For example, variables of type double should be declared before variables of type int which should, in turn, be declared before variables of type Node.
Variables (other than index variables in loops) must not be declared and initialized in a single statement.
For example, you must not have statements like int i = 0;. (Though this is inconvenient in some situations, it prevents a common mistake made by beginning programmers.)
Each class must have a descriptive block comment.
This comment should describe the complete class (rather than the methods in the class).
Each method/function must have a descriptive block comment.
This comment should describe the methods, its parameters, and its return value.

Block comments must use the javadoc format.

javadoc is a program (written in Java) that creates external documentation (in HTML) from block comments. All of the Java documentation was, in fact, created this way. javadoc block comments start with /** and end with */.

javaexamples/JavadocExample.java

/**
 * This is where the description of the class goes.  
 * You can include HTML tags if you would like.
 *
 * @author      Author's name
 * @version     Version number
 *
 *
 * This work complies with the JMU Honor Code.
 */
public class ClassName
{


    /**
     * This is where the description of the method goes.
     *
     * @param param1    Description of the first parameter
     * @param param2    Description of the second parameter
     * @return          Description of what is returned
     */
     public ReturnType methodName(Type1 param1, Type2 param2)
    {

    }


}

Comments in the body of a class should use // rather than /* ... */.
This isn't a requirement but it will make your life easier since you can't nest comments inside of /* ... */. There is nothing more annoying then trying to "comment out" a section of code while you are debugging and being unable to because it contains block comments.
In the block comment for each class you must include a comment attesting to your compliance with the JMU Honor Code as follows:
```
	 *
	 * This work complies with the JMU Honor Code.
	 *
         
```
In the block comment for each class you must include an @author element.
Use indentation and use it consistently.
No particular indentation scheme is required but you must indent your code in a meaningful and consistent way.

2 Other Style Guides

Different people have different opinions about what is "stylish". If you are interested in such things (and you should be) you might want to take a look at:

3 Style Humor

As mentioned above, different people have different opinions about what is "stylish". This leads to many fights (and some jokes).

../lectures/comics/Hackles-Style.png
(Courtesy of Hackles)

(Courtesy of xkcd)